<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="umsroot.css">
<TITLE>
Extending the Debugger
</TITLE>
</HEAD>
<BODY >
<A HREF="umsroot080.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot074.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot082.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc201">14.7</A>&nbsp;&nbsp;Extending the Debugger</H2><UL>
<LI><A HREF="umsroot081.html#toc122">User-defined Ports</A>
<LI><A HREF="umsroot081.html#toc123">Attaching a Different User Interface</A>
</UL>


<A NAME="toc122"></A>
<H3 CLASS="subsection"><A NAME="htoc202">14.7.1</A>&nbsp;&nbsp;User-defined Ports</H3>
The standard set of ports in the debugger's box model can be extended by
the programmer. This facility is not so much intended for applications,
but rather for libraries that want to allow debugging in terms of
concepts of the library. Specific ports can be used to identify the
interesting events during execution of the library code (while the standard
tracing of the library internals can be suppressed by compiling the
library in nodebug-mode).<BR>
<BR>
The system provides 4 primitives that can generate 4 kinds of box model ports.
When inserted into the code, and when the debugger is on,
they will cause execution to stop and enter the debugger,
displaying a trace line with the user-defined port and data:
<UL CLASS="itemize"><LI CLASS="li-itemize">
<A HREF="../bips/kernel/debug/trace_call_port-3.html"><B>trace_call_port(+Port, ?Invoc, ?Term)</B></A><A NAME="@default857"></A>
	is used to create new ports similar to CALL ports, but the port name
	can be chosen freely. Such a port creates a new box. There must be
	a corresponding trace_exit_port/0 to exit the box on success.
<LI CLASS="li-itemize"><A HREF="../bips/kernel/debug/trace_exit_port-0.html"><B>trace_exit_port</B></A><A NAME="@default858"></A>
	is used in conjunction with trace_call_port/3 to exit a box
	on success.
<LI CLASS="li-itemize"><A HREF="../bips/kernel/debug/trace_point_port-3.html"><B>trace_point_port(+Port, ?Invoc, ?Term)</B></A><A NAME="@default859"></A>
	is used to create a standalone port, i.e. a port that causes the
	tracer to create a trace line, but does not create, enter or leave
	any box.
<LI CLASS="li-itemize"><A HREF="../bips/kernel/debug/trace_parent_port-1.html"><B>trace_parent_port(+Port)</B></A><A NAME="@default860"></A>
	is used to create an additional port for the parent box, but does
	not enter or leave the box.
</UL>
For example, trace_call_port/3 and trace_exit_port/0 can be used to
create a more readable trace in the presence of source
transformations. Imagine that the goal <TT>Y is X*X-1</TT>
has been flattened into the goal sequence <TT>*(X,X,T),-(T,1,Y)</TT>. 
By inserting the trace primitives the debugger can still show the
original source before transformation:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
p(X,Y) :- 
        trace_call_port(call,_, Y is X*X-1),
        *(X,X,T),
        -(T,1,Y),
        trace_exit_port.
</PRE></BLOCKQUOTE>
The trace then looks like this:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
[eclipse 8]: p(3,Y).
(1) 1 CALL  p(3, Y)   %&gt; creep
(2) 2 CALL  Y is 3 * 3 - 1   %&gt; skip
(2) 2 EXIT  8 is 3 * 3 - 1   %&gt; creep
(1) 1 EXIT  p(3, 8)   %&gt; creep
Y = 8
</PRE></BLOCKQUOTE>
Another example is the insertion of additional ports for existing boxes,
in particular the current parent box:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
p :-
        trace_parent_port(clause1),  
        writeln(hello),
        fail.
p :-
        trace_parent_port(clause2),  
        writeln(world).
</PRE></BLOCKQUOTE>
This gives rise to the following trace:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
?- p.
  (1) 1 CALL  p   %&gt; creep
  (1) 1 CLAUSE1  p   %&gt; creep
S (2) 2 CALL  writeln(hello)   %&gt; creep
hello
S (2) 2 EXIT  writeln(hello)   %&gt; creep
  (3) 2 CALL  fail   %&gt; creep
  (3) 2 FAIL  fail   %&gt; creep
  (1) 1 NEXT  p   %&gt; creep
  (1) 1 CLAUSE2  p   %&gt; creep
S (4) 2 CALL  writeln(world)   %&gt; creep
world
S (4) 2 EXIT  writeln(world)   %&gt; creep
  (1) 1 EXIT  p   %&gt; creep
Yes (0.00s cpu)
</PRE></BLOCKQUOTE>
Note that the additional ports share the parent's invocation number,
so the <B>i</B> command can be used to skip from one to the other.<BR>
<BR>
<A NAME="toc123"></A>
<H3 CLASS="subsection"><A NAME="htoc203">14.7.2</A>&nbsp;&nbsp;Attaching a Different User Interface</H3>
The tracer consists of a <B>trace generation</B> component (which is part of the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> runtime kernel), and a <B>user interface</B> (which is part of the
development system). The standard ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> distribution contains two
user interfaces, a console-based one, and a graphical one which is part
of <B>tkeclipse</B>. A programmable tracer interface (OPIUM/LSD) is under
development in the group of Mireille Ducasse at IRISA/Rennes.
Connecting new interfaces is relatively easy, for more detailed
information contact the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> development team.<BR>
<BR>
<HR>
<A HREF="umsroot080.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="umsroot074.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="umsroot082.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
